nonlin_types.f90 Source File


Source Code

! MIT License
!
! Copyright (c) 2017-2026 Jason Christopherson
!
! Permission is hereby granted, free of charge, to any person obtaining a copy
! of this software and associated documentation files (the "Software"), to deal
! in the Software without restriction, including without limitation the rights
! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
! copies of the Software, and to permit persons to whom the Software is
! furnished to do so, subject to the following conditions:
!
! The above copyright notice and this permission notice shall be included in all
! copies or substantial portions of the Software.
!
! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
! SOFTWARE.
!
module nonlin_types
    use iso_fortran_env
    use ieee_arithmetic, only : ieee_value, ieee_quiet_nan
    use nonlin_error_handling
    implicit none
    private
    public :: convergence_history
    public :: iteration_behavior
    public :: value_pair

    type convergence_history
        !! A collection of arrays providing solver-related data from each
        !! iteration.
        real(real64), allocatable, dimension(:) :: log_residual
            !! Base-10 logarithm of the residual norm at each iteration.
        real(real64), allocatable, dimension(:) :: log_step_change
            !! Base-10 logarithm of the norm of the direction vector for each
            !! iteration.
        real(real64), allocatable, dimension(:) :: log_gradient
            !! Base-10 logarithm of the norm of the gradient for each iteration.
    end type

    type iteration_behavior
        !! Defines a set of parameters that describe the behavior of the
        !! iteration process.
        integer :: iter_count
            !! Specifies the number of iterations performed.
        integer :: fcn_count
            !! Specifies the number of function evaluations performed.
        integer :: jacobian_count
            !! Specifies the number of Jacobian evaluations performed.
        integer :: gradient_count
            !! Specifies the number of gradient vector evaluations performed.
        logical :: converge_on_fcn
            !! True if the solution converged as a result of a zero-valued
            !! function; else, false.
        logical :: converge_on_chng
            !! True if the solution converged as a result of no appreciable
            !! change in solution points between iterations; else, false.
        logical :: converge_on_zero_diff
            !! True if the solution appears to have settled on a stationary
            !! point such that the gradient of the function is zero-valued; 
            !! else, false.
        type(convergence_history), private :: m_history
            !! Convergence history.
        integer, private :: m_history_count = 0
            !! Counter for the actual number of items in the m_history arrays.
    contains
        procedure, public :: initialize => ib_init
        procedure, private :: is_history_allocated => ib_is_history_allocated
        procedure, private :: allocate_history_arrays => ib_allocate_history
        procedure, private :: get_history_buffer_size => ib_get_history_buffer_size
        procedure, private :: reallocate_history_arrays => ib_reallocate_history_storage
        procedure, public :: log_iteration => ib_log_iteration
        procedure, public :: get_convergence_history => ib_get_history
    end type

    interface iteration_behavior
        module procedure :: ib_constructor
    end interface

    type value_pair
        !! Defines a pair of numeric values.
        real(real64) :: x1
            !! Value 1.
        real(real64) :: x2
            !! Value 2.
    end type

contains
! ******************************************************************************
! ITERATION_BEHAVIOR PROCEDURES
! ------------------------------------------------------------------------------
    subroutine ib_init(this, max_iters)
        !! Initializes the [[iteration_behavior]] object.  All fields are reset
        !! such that all counters are zero and all convergence flags are false.
        class(iteration_behavior), intent(inout) :: this
            !! The [[iteration_behavior]] object.
        integer, intent(in) :: max_iters
            !! The maximum number of iterations the solver is allowed to take.
            !! An NL_INVALID_INPUT_ERROR is thrown if this value is less than
            !! one.

        if (max_iters < 1) error stop NL_INVALID_INPUT_ERROR

        this%converge_on_chng = .false.
        this%converge_on_fcn = .false.
        this%converge_on_zero_diff = .false.
        this%fcn_count = 0
        this%gradient_count = 0
        this%iter_count = 0
        this%jacobian_count = 0

        this%m_history_count = 0
        call this%allocate_history_arrays(max_iters)
    end subroutine

! ------------------------------------------------------------------------------
    function ib_constructor(max_iters) result(rst)
        !! Initializes the [[iteration_behavior]] object.  All fields are set
        !! such that all counters are zero and all convergence flags are false.
        integer, intent(in) :: max_iters
            !! The maximum number of iterations the solver is allowed to take.
            !! An NL_INVALID_INPUT_ERROR is thrown if this value is less than
            !! one.
        type(iteration_behavior) :: rst
            !! The [[iteration_behavior]] object.

        call rst%initialize(max_iters)
    end function

! ------------------------------------------------------------------------------
    pure function ib_is_history_allocated(this) result(rst)
        !! Tests to see if the m_history arrays are allocated.
        class(iteration_behavior), intent(in) :: this
            !! The [[iteration_behavior]] object.
        logical :: rst
            !! True if all of the arrays are allocated; else, false.

        rst = allocated(this%m_history%log_gradient) .and. &
            allocated(this%m_history%log_residual) .and. &
            allocated(this%m_history%log_step_change)
    end function

! ------------------------------------------------------------------------------
    subroutine ib_allocate_history(this, n)
        !! Allocates the history array to the requested size.
        class(iteration_behavior), intent(inout) :: this
            !! The [[iteration_behavior]] object.
        integer, intent(in) :: n
            !! The size.

        real(real64) :: nan
        nan = ieee_value(nan, ieee_quiet_nan)

        if (allocated(this%m_history%log_gradient)) deallocate(this%m_history%log_gradient)
        if (allocated(this%m_history%log_residual)) deallocate(this%m_history%log_residual)
        if (allocated(this%m_history%log_step_change)) deallocate(this%m_history%log_step_change)
        allocate( &
            this%m_history%log_gradient(n), &
            this%m_history%log_residual(n), &
            this%m_history%log_step_change(n), &
            source = nan &
        )
    end subroutine

! ------------------------------------------------------------------------------
    pure function ib_get_history_buffer_size(this) result(rst)
        !! Gets the size of the history buffers.
        class(iteration_behavior), intent(in) :: this
            !! The [[iteration_behavior]] object.
        integer :: rst
            !! The size.

        if (.not.this%is_history_allocated()) then
            rst = 0
        else
            rst = min( &
                size(this%m_history%log_gradient), &
                size(this%m_history%log_residual), &
                size(this%m_history%log_step_change) &
            )
        end if
    end function

! ------------------------------------------------------------------------------
    subroutine ib_reallocate_history_storage(this, new_size)
        !! Reallocates storage for the history buffers.
        class(iteration_behavior), intent(inout) :: this
            !! The [[iteration_behavior]] object.
        integer :: new_size
            !! The new size of the storage arrays.

        integer :: n
        real(real64), allocatable, dimension(:) :: g, r, x

        if (.not.this%is_history_allocated()) then
            ! Simply allocate as nothing is allocated yet
            call this%allocate_history_arrays(new_size)
        else
            ! Resize each array
            call move_alloc(this%m_history%log_gradient, g)
            call move_alloc(this%m_history%log_residual, r)
            call move_alloc(this%m_history%log_step_change, x)
            call this%allocate_history_arrays(new_size)
            n = size(g)
            this%m_history%log_gradient(1:n) = g
            this%m_history%log_residual(1:n) = r
            this%m_history%log_step_change(1:n) = x
        end if
    end subroutine

! ------------------------------------------------------------------------------
    subroutine ib_log_iteration(this, resid, dx, grad)
        !! Registers an iteration given the appropriate metrics.
        class(iteration_behavior), intent(inout) :: this
            !! The [[iteration_behavior]] object.
        real(real64), intent(in) :: resid
            !! The residual value.
        real(real64), intent(in) :: dx
            !! The norm of the solution direction vector.
        real(real64), intent(in) :: grad
            !! The norm of the gradient vector.

        this%m_history_count = this%m_history_count + 1
        if (this%m_history_count > this%get_history_buffer_size()) then
            call this%reallocate_history_arrays(this%m_history_count + 100)
        end if

        this%m_history%log_residual(this%m_history_count) = log10(resid)
        this%m_history%log_step_change(this%m_history_count) = log10(dx)
        this%m_history%log_gradient(this%m_history_count) = log10(grad)
    end subroutine

! ------------------------------------------------------------------------------
    pure function ib_get_history(this) result(rst)
        !! Gets the convergence history.
        class(iteration_behavior), intent(in) :: this
            !! The [[iteration_behavior]] object.
        type(convergence_history) :: rst
            !! The [[convergence_history]] object containing convergence 
            !! tracking information.

        integer :: n

        if (this%m_history_count == 0) then
            allocate(rst%log_gradient(0), rst%log_residual(0), rst%log_step_change(0))
        else
            n = this%m_history_count
            allocate(rst%log_gradient(n), source = this%m_history%log_gradient(1:n))
            allocate(rst%log_residual(n), source = this%m_history%log_residual(1:n))
            allocate(rst%log_step_change(n), source = this%m_history%log_step_change(1:n))
        end if
    end function

! ------------------------------------------------------------------------------
end module